home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / dist6.4 / pcp.idb / usr / share / catman / u_man / cat3 / PMAPI / pmdainit.z.z / pmdainit.z / pmdainit
Text File  |  1997-04-03  |  11KB  |  199 lines
  1.  
  2.  
  3.  
  4. PPPPMMMMDDDDAAAAIIIINNNNIIIITTTT((((3333))))                                                        PPPPMMMMDDDDAAAAIIIINNNNIIIITTTT((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ppppmmmmddddaaaaIIIInnnniiiitttt - initialize a PMDA
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmaaaappppiiii....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////iiiimmmmppppllll....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmddddaaaa....hhhh>>>>
  15.  
  16.      iiiinnnntttt ppppmmmmddddaaaaIIIInnnniiiitttt((((ppppmmmmddddaaaaIIIInnnntttteeeerrrrffffaaaacccceeee ****ddddiiiissssppppaaaattttcccchhhh,,,, ppppmmmmddddaaaaIIIInnnnddddoooommmm ****iiiinnnnddddoooommmmssss,,,, iiiinnnntttt nnnniiiinnnnddddoooommmmssss,,,,
  17.      ppppmmmmddddaaaaMMMMeeeettttrrrriiiicccc ****mmmmeeeettttrrrriiiiccccssss,,,, iiiinnnntttt nnnnmmmmeeeettttrrrriiiiccccssss))))
  18.  
  19.      cccccccc ............ ----llllppppccccpppp____ppppmmmmddddaaaa ----llllppppccccpppp
  20.  
  21. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  22.      ppppmmmmddddaaaaIIIInnnniiiitttt initializes a PMDA so that it is ready to receive PDUs from
  23.      ppppmmmmccccdddd(1).  The function expects as arguments the instance domain table
  24.      (_i_n_d_o_m_s) and the metric description table (_m_e_t_r_i_c_s) that are initialized
  25.      by the PMDA. The arguments _n_i_n_d_o_m_s and _n_m_e_t_r_i_c_s should be set to the
  26.      number of instances and metrics in the tables, respectively.
  27.  
  28.      Much of the ppppmmmmddddaaaaIIIInnnntttteeeerrrrffffaaaacccceeee structure can be automatically initialized with
  29.      ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3), ppppmmmmddddaaaaGGGGeeeettttOOOOpppptttt(3) and ppppmmmmddddaaaaDDDDSSSSOOOO(3).  ppppmmmmddddaaaaIIIInnnniiiitttt completes the PMDA
  30.      initialization phase with three operations.  The first operation adds the
  31.      domain and instance numbers to the instance and metric tables.  Singular
  32.      metrics (metrics without an instance domain) should have the instance
  33.      domain PPPPMMMM____IIIINNNNDDDDOOOOMMMM____NNNNUUUULLLLLLLL set in the _i_n_d_o_m field of the ppppmmmmDDDDeeeesssscccc structure (see
  34.      ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3)).  Metrics with an instance domain should set this field
  35.      to be the serial number of the instance domain in the _i_n_d_o_m_s table.
  36.  
  37. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  38.      For example, a PMDA has three metrics: A, B and C, and two instance
  39.      domains X and Y, with two instances in each instance domain.  The
  40.      instance domain and metrics description tables could be defined as:
  41.  
  42.           static pmdaInstid _X[] = {
  43.               { 0, "X1" }, { 1, "X2" }
  44.           };
  45.  
  46.           static pmdaInstid _Y[] = {
  47.               { 0, "Y1" }, { 1, "Y2" }
  48.           };
  49.  
  50.           static pmdaIndom indomtab[] = {
  51.           #define X_INDOM 0
  52.               { X_INDOM, 2, _X },
  53.           #define Y_INDOM 3
  54.               { Y_INDOM, 2, _Y }
  55.           };
  56.  
  57.           static pmdaMetric metrictab[] = {
  58.           /* A */
  59.               { (void *)0,
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPMMMMDDDDAAAAIIIINNNNIIIITTTT((((3333))))                                                        PPPPMMMMDDDDAAAAIIIINNNNIIIITTTT((((3333))))
  71.  
  72.  
  73.  
  74.                 { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
  75.                   { 0,0,0,0,0,0} }, },
  76.           /* B */
  77.               { (void *)0,
  78.                 { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
  79.                   { 0,0,0,0,0,0} }, },
  80.           /* C */
  81.               { (void *)0,
  82.                 { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
  83.                   { 0,1,0,0,PM_TIME_SEC,0} }, }
  84.           };
  85.  
  86.      The metric description table defines metric A with no instance domain,
  87.      metric B with instance domain X and metric C with instance domain Y.
  88.      Metric C has units of seconds, while the other metrics have no units
  89.      (simple counters).  ppppmmmmddddaaaaIIIInnnniiiitttt will take these structures and assign the
  90.      PPPPMMMMDDDDAAAA(3) domain number to the _i_t__i_n_d_o_m field of each instance domain.
  91.      This identifier also replaces the _i_n_d_o_m field of all metrics which have
  92.      that instance domain, so that they are correctly associated.
  93.  
  94.      The second stage opens the nnnnddddbbbbmmmm(3) help text file, if one was specified
  95.      with the ----BBBB command line options (see ppppmmmmddddaaaaGGGGeeeettttOOOOpppptttt(3)) or as an argument to
  96.      ppppmmmmddddaaaaDDDDSSSSOOOO(3) or ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3).
  97.  
  98.      The final stage determines if the metrics can be directly mapped to the
  99.      metric table using their unique identifiers.  If all of the metric PMID
  100.      item numbers correspond to the position in the _m_e_t_r_i_c_s table, then direct
  101.      mapping is used.  This can greatly improve the efficiency of the callback
  102.      functions.
  103.  
  104. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  105.      ppppmmmmddddaaaaIIIInnnniiiitttt will set _d_i_s_p_a_t_c_h->_s_t_a_t_u_s to a value less than zero if there is
  106.      an error that should prevent the PPPPMMMMDDDDAAAA(3) from successfully running.
  107.      ppppmmmmccccdddd(1) will terminate the connection to the PPPPMMMMDDDDAAAA(3) if this occurs.
  108.  
  109.      ppppmmmmddddaaaaIIIInnnniiiitttt may issue any of these messages:
  110.  
  111.      PPPPMMMMDDDDAAAA pppprrrroooottttooooccccoooollll vvvveeeerrrrssssiiiioooonnnn _p_r_o_t_o_c_o_l nnnnooootttt ssssuuuuppppppppoooorrrrtttteeeedddd
  112.                     The _p_r_o_t_o_c_o_l version is not supported by ppppmmmmddddaaaaIIIInnnniiiitttt.
  113.  
  114.      UUUUssssiiiinnnngggg ppppmmmmddddaaaaFFFFeeeettttcccchhhh(((()))) bbbbuuuutttt ffffeeeettttcccchhhh ccccaaaallllllll bbbbaaaacccckkkk
  115.                     The fetch callback, ppppmmmmddddaaaaFFFFeeeettttcccchhhh(3), requires an additional
  116.                     callback to be provided using ppppmmmmddddaaaaSSSSeeeettttFFFFeeeettttcccchhhhCCCCaaaallllllllBBBBaaaacccckkkk(3).
  117.  
  118.      IIIIlllllllleeeeggggaaaallll iiiinnnnssssttttaaaannnncccceeee ddddoooommmmaaaaiiiinnnn _i_n_s_t ffffoooorrrr mmmmeeeettttrrrriiiicccc _p_m_i_d
  119.                     The instance domain _i_n_s_t that was specified for metric
  120.                     _p_m_i_d is not within the range of the instance domain table.
  121.  
  122.      NNNNoooo hhhheeeellllpppp tttteeeexxxxtttt ppppaaaatttthhhh ssssppppeeeecccciiiiffffiiiieeeedddd
  123.                     The help text callback, ppppmmmmddddaaaaTTTTeeeexxxxtttt(3), requires a nnnnddddbbbbmmmm(3)
  124.                     data base containing the help text for the metrics to have
  125.                     been opened.  No path to the help text was specified as a
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPMMMMDDDDAAAAIIIINNNNIIIITTTT((((3333))))                                                        PPPPMMMMDDDDAAAAIIIINNNNIIIITTTT((((3333))))
  137.  
  138.  
  139.  
  140.                     command line option, or as an argument to ppppmmmmddddaaaaDDDDSSSSOOOO(3) or
  141.                     ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3).  This message is only a warning.
  142.  
  143.      DDDDiiiirrrreeeecccctttt mmmmaaaappppppppiiiinnnngggg ffffoooorrrr mmmmeeeettttrrrriiiiccccssss ddddiiiissssaaaabbbblllleeeedddd @@@@ _n_u_m
  144.                     The unit numbers of the metrics did not correspond to the
  145.                     index in the metric description table.  The direct mapping
  146.                     failed for metric number _n_u_m in the _m_e_t_r_i_c_s table.  This
  147.                     is less efficient but is not fatal and the message is only
  148.                     a warning.
  149.  
  150. CCCCAAAAVVVVEEEEAAAATTTT
  151.      The PMDA must be using PPPPMMMMDDDDAAAA____PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL____2222 or later, as specified in the call
  152.      to ppppmmmmddddaaaaDDDDSSSSOOOO(3) or ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3).
  153.  
  154. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  155.      ppppmmmmccccdddd(1), nnnnddddbbbbmmmm(3), PPPPMMMMDDDDAAAA(3), ppppmmmmddddaaaaDDDDaaaaeeeemmmmoooonnnn(3), ppppmmmmddddaaaaDDDDSSSSOOOO(3), ppppmmmmddddaaaaGGGGeeeettttOOOOpppptttt(3),
  156.      ppppmmmmddddaaaaFFFFeeeettttcccchhhh(3), ppppmmmmddddaaaaTTTTeeeexxxxtttt(3), and ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3).
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.